<?php
/**
 * Zend Framework
 *
 * LICENSE
 *
 * This source file is subject to the new BSD license that is bundled
 * with this package in the file LICENSE.txt.
 * It is also available through the world-wide-web at this URL:
 * http://framework.zend.com/license/new-bsd
 * If you did not receive a copy of the license and are unable to
 * obtain it through the world-wide-web, please send an email
 * to license@zend.com so we can send you a copy immediately.
 *
 * @category   Zend
 * @package    Zend_Queue
 * @subpackage Adapter
 * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 * @version    $Id: AdapterInterface.php 18951 2009-11-12 16:26:19Z alexander $
 */

/**
 * Interface for common queue operations
 *
 * @category   Zend
 * @package    Zend_Queue
 * @subpackage Adapter
 * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */
interface Zend_Queue_Adapter_AdapterInterface
{
	/**
	 * Constructor
	 *
	 * @param  array|Zend_Config $options
	 * @param  Zend_Queue $queue
	 * @return void
	 */
	public function __construct($options, Zend_Queue $queue = null);

	/**
	 * Retrieve queue instance
	 *
	 * @return Zend_Queue
	 */
	public function getQueue();

	/**
	 * Set queue instnace
	 *
	 * @param  Zend_Queue $queue
	 * @return Zend_Queue_Adapter_AdapterInterface
	 */
	public function setQueue(Zend_Queue $queue);

	/**
	 * Does a queue already exist?
	 *
	 * Use isSupported('isExists') to determine if an adapter can test for
	 * queue existance.
	 *
	 * @param  string $name Queue name
	 * @return boolean
	 */
	public function isExists($name);

	/**
	 * Create a new queue
	 *
	 * Visibility timeout is how long a message is left in the queue
	 * "invisible" to other readers.  If the message is acknowleged (deleted)
	 * before the timeout, then the message is deleted.  However, if the
	 * timeout expires then the message will be made available to other queue
	 * readers.
	 *
	 * @param  string  $name Queue name
	 * @param  integer $timeout Default visibility timeout
	 * @return boolean
	 */
	public function create($name, $timeout=null);

	/**
	 * Delete a queue and all of its messages
	 *
	 * Return false if the queue is not found, true if the queue exists.
	 *
	 * @param  string $name Queue name
	 * @return boolean
	 */
	public function delete($name);

	/**
	 * Get an array of all available queues
	 *
	 * Not all adapters support getQueues(); use isSupported('getQueues')
	 * to determine if the adapter supports this feature.
	 *
	 * @return array
	 */
	public function getQueues();

	/**
	 * Return the approximate number of messages in the queue
	 *
	 * @param  Zend_Queue|null $queue
	 * @return integer
	 */
	public function count(Zend_Queue $queue = null);

	/********************************************************************
	 * Messsage management functions
	 *********************************************************************/

	/**
	 * Send a message to the queue
	 *
	 * @param  mixed $message Message to send to the active queue
	 * @param  Zend_Queue|null $queue
	 * @return Zend_Queue_Message
	 */
	public function send($message, Zend_Queue $queue = null);

	/**
	 * Get messages in the queue
	 *
	 * @param  integer|null $maxMessages Maximum number of messages to return
	 * @param  integer|null $timeout Visibility timeout for these messages
	 * @param  Zend_Queue|null $queue
	 * @return Zend_Queue_Message_Iterator
	 */
	public function receive($maxMessages = null, $timeout = null, Zend_Queue $queue = null);

	/**
	 * Delete a message from the queue
	 *
	 * Return true if the message is deleted, false if the deletion is
	 * unsuccessful.
	 *
	 * @param  Zend_Queue_Message $message
	 * @return boolean
	 */
	public function deleteMessage(Zend_Queue_Message $message);

	/********************************************************************
	 * Supporting functions
	 *********************************************************************/

	/**
	 * Returns the configuration options in this adapter.
	 *
	 * @return array
	 */
	public function getOptions();

	/**
	 * Return a list of queue capabilities functions
	 *
	 * $array['function name'] = true or false
	 * true is supported, false is not supported.
	 *
	 * @return array
	 */
	public function getCapabilities();

	/**
	 * Indicates if a function is supported or not.
	 *
	 * @param  string $name Function name
	 * @return boolean
	 */
	public function isSupported($name);
}
